Reads a file's text into a variable.
FileRead, OutputVar, Filename
| OutputVar | The name of the variable in which to store the retrieved text. OutputVar will be made blank if a problem occurs such as the file being "in use" or not existing (in which case ErrorLevel is set to 1). It will also be made blank if Filename is an empty file (in which case ErrorLevel is set to 0). |
| Filename | The name of the file to read, which is assumed to be in %A_WorkingDir% if an absolute path isn't specified. Options: Zero or more of the following strings may be also be present immediately before the name of the file. Separate each option from the next with a single space or tab. For example: *t *m5000 C:\Log Files\200601.txt *c: Load a ClipboardAll file. All other options are ignored when *c is present. *m1024 [v1.0.43.03+]: If this option is omitted, the entire file is loaded unless the file is larger than 1 GB, in which case it is not loaded at all. Otherwise, replace 1024 with a decimal or hexadecimal number of bytes between 1 and 1073741824 (1 GB). If the file is larger than this, only its leading part is loaded. Note: This might result in the last line ending in a naked carriage return (`r) rather than `r`n. *t: Replaces any/all occurrences of carriage return & linefeed (`r`n) with linefeed (`n). However, this translation reduces performance and is usually not necessary. For example, text containing `r`n is already in the right format to be added to a Gui Edit control. Similarly, FileAppend detects the presence of `r`n when it opens a new file; it knows to write each `r`n as-is rather than translating it to `r`r`n. Finally, the following parsing loop will work correctly regardless of whether each line ends in `r`n or just `n: Loop, parse, MyFileContents, `n, `r |
ErrorLevel is set to 0 if the load was successful. It is set to 1 if a problem occurred such as: 1) file does not exist; 2) file is locked or inaccessible; 3) the system lacks sufficient memory to load the file.
When the goal is to load all or most of a file into memory, FileRead performs much better than using a file-reading loop.
A file greater than 1 GB in size will cause ErrorLevel to be set to 1 and OutputVar to be made blank unless the *m option is present, in which case the leading part of the file is loaded.
FileRead does not obey #MaxMem. If there is concern about using too much memory, check the file size beforehand with FileGetSize.
If the specified file contains any binary zeros (which never occur in proper text files), only the text before the first binary zero will be "seen" by AutoHotkey commands and functions. However, the entire contents are still present in OutputVar and can be accessed by advanced methods such as the address operator (&); for example: *(&OutputVar + 1000)
FileRead can be used to quickly sort the contents of a file as in the following example:
FileRead, Contents, C:\Address List.txt if not ErrorLevel ; Successfully loaded. { Sort, Contents FileDelete, C:\Address List (alphabetical).txt FileAppend, %Contents%, C:\Address List (alphabetical).txt Contents = ; Free the memory. }
file-reading loop, FileReadLine, FileGetSize, FileAppend, IniRead, Sort, UrlDownloadToFile
FileRead, OutputVar, C:\My Documents\My File.txt